Macwelt 1/Macwelt DVD 1.toast/Web-Publishing/HTML-Editoren/Alpha ƒ/Help/Macros Help

Text File | 2000-12-06 | 14.1 KB | 293 lines

Keyboard Macros Help

                                               version: 0.2
                                               created: 05/19/00 {11:44:50 am}
                                           last update: 12/06/00 {12:07:38 pm}


          What Is a Macro?

A macro is a sequence of recorded keystrokes that can be played back again.
Unlike other macro packages you might be familiar with in other Mac
applications, keyboard macros in Alpha do not record mouse movement or menu
selection; only keystrokes are recorded.  Even with this limitation, you
will discover that macros can save you time through easy automation of
repetitive tasks.  When do you make a macro?  Whenever you find yourself
typing the same keystrokes over and over again, then a light should go off
in your brain telling you its time to make a macro.  Once you make a macro,
you can name it (that is, save it) for future use.  Over time you will
build up a library of macros that you can invoke any time you need them.

Things you can do with macros:

    *    basic textual markup
    *    reformat tables and files
    *    complex copying and pasting between edit windows

Alpha's implementation of macros is similar to that of Emacs, but there are
subtle differences.  Remember, Alpha is not Emacs!  You don't need to be an
Emacs guru to use keyboard macros in Alpha.  Since macros are a simple way
of creating valid Alpha text manipulation commands, every user will benefit
from a basic working knowledge of how to use macros.

          Defining a Macro

Defining keyboard macros can be done with the Kbd Macros submenu in the Utils
menu.  The Kbd Macros submenu has the following items

    Menu Item                 | Keystroke            | Action
    _________________________________________________________________________
    Start Keyboard Macro    | C-x ( or F13        | Start recording keystrokes.
    End Keyboard Macro        | C-x ) or F14        | End recording.
    Execute Keyboard Macro    | C-x e    or F15        | Invoke last macro.
    _________________________________________________________________________
    Name Last Macro            | (none)            | Save last macro.
    Delete Named Macro        | (none)            | Delete a saved macro.
    Dump Named Macro        | (none)            | Prints the macro sequence
                            |                    | as a list of Alpha commands
                            |                    | in an open window.

The last item is the Macros submenu that lists all the named macros.  Named
macros may be invoked by selecting them from this submenu.

If you don't have an extended keyboard, begin recording a macro by typing
C-x (.  The message "Defining Keyboard Macro ..."  will appear in the status
bar to inform you that your subsequent keystrokes will be recorded.  Once
you have started a keyboard macro Alpha will record everything you type:
commands and literal text.  Remember, nothing you do with the mouse is
recorded, so you should move the point with cursor movement bindings.  (See
Emacs.help for a list of Emacs cursor movement bindings.)  To end
the macro, type C-x ); this tells Alpha to stop recording your keystrokes.
A recording session will terminate automatically if there is an error or
if you abort the macro by typing C-g (abortEm).

During macro recording, Alpha behaves normally responding to commands and
keystrokes; thus you will be able to see if your keystrokes are
appropriate.  If you make a mistake, unless it is a fatal one, you can
probably just type some extra corrective keystrokes and continue.  Macros
run so quickly that executing a few superfluous keystrokes will not
noticeably effect your macro's performance.  Of course you can always abort
the macro recording if you can remember the keystrokes you need.  Editing
a macro is not easy (but it can be done, instructions for advanced users
will follow in the section "Editing Named Macros").

To invoke your macro after you have recorded it, type C-x e
(executeKeyboardMacro).  Alpha will play back your keystrokes.  C-x e
invokes only the last recorded macro.  If you record a new macro without
naming the last macro, the last macro will be overwritten and lost.  Any
macro you want to save should be named.

          An Example:  Double-Space Macro

A very simple example of a keyboard macro is the classic double-space
macro.  This macro when applied repeatedly to lines of text will insert
spaces between the lines: useful if you want to print out a draft for
editing.

Begin recording by selecting "Start Keyboard Macro" or typing C-x (.  Move
to the end of the current line with C-e.  Press the return key.  Move to
the next line, C-f, to position the insertion point proper incase the macro
is called multiple times with C-u.  Now end the macro by selecting "End
Keyboard Macro" or typing C-x ).

Copy the following text and paste into a new window to practice.

    Alpha is multi-modal, which means it switches between different modes
    depending on what type of document you are editing.  Everybody who has
    used Emacs knows about this concept.  A mode customizes Alpha's
    behavior to assist you to create and edit documents of the mode...
    (from the Alpha Manual)

Defining the macro has inserted a space between the first two lines.  Now
you will want to double-space the rest of the paragraph.  You can use C-u
(iterationCount).  The text "C-u" appears in the status bar.  The next
thing you type will be the number of times you want a command repeated.
There are three more lines in the example text so type 3, then C-x e to
invoke the macro you just defined.  (Note for Emacs users: typing C-u
is the same as typing C-u 4; however typing C-u more than
once does not result in the standard multiplication.  C-u C-u C-u C-x e
DOES NOT result in 56 executes.)  If you want to find out how many times
to repeat the double-space macro, select the region of text you want to
double-space; type ESC-x (execute) (that is type and release the escape key, then
type x); the text "M-x" will appear in the status bar; now type the
command "wordCount" into the status bar and hit return.  The number of
chars, words, and lines in the selected region will be returned.  If you
don't select a region the numbers for the entire file will be returned.

If you want to use this macro again in the future, you should name it.
Select "Name Last Macro" and enter something meaningful.  You should not
use any special characters or spaces in the macro name since the macro
will be saved as a Tcl procedure.  Since your macro will be a Tcl
procedure like any other, you should avoid naming it anything that will
conflict with another Alpha or Tcl command.  (NOTE to the developers: why
not catch $name in nameLastMacro to see if it is a valid entry and if it
already exists as a procedure name?)  All of your named macros will appear
in the Macros submenu.  Since your macros are valid Tcl procedures you can
define key-bindings for them.  (How about a procedure to automatically add
bindings for macros to the prefs.tcl file?)  For the double-spacing macro,
let's call it dblspace1.

Now, let's suppose that you have several named macros.  C-x e will execute
only the current (last recorded) macro not one of the previously named
macros.  One strategy is to trick Alpha into making a named macro the
current macro by re-recording it.  This is not very difficult.  Just type
C-x (, select the named macro from the Macros submenu, then type C-x ) to
end recording.  You don't have to enter in all the keystrokes again.  Now
that your named macro is once again the current macro you may invoke it
with C-x e.  This is useful if you want to combine C-x e with C-u to
invoke the macro multiple times.  (Note to the developers: what about
adding a "Select Current Macro" item and rebind C-x e to invoke whatever is
in the currentMacro global variable?)

          A More Complex Example: Copy Sentence to Another File

This example is a little complicated, but it will show you how to add a
search to a macro.

This macro copies the sentence that contains the point and pastes (yanks)
it into a file named 'AlphaRefs'.  You can run this macro on this file if
you would like to test it.  First, you will need to open a new edit window
entitled 'AlphaRefs'.  (If you have the New Document package activated,
just hit cmd-n and type in the name; otherwise you will have to save the
empty file in order to name it.)

    Keystrokes                | Action
    _________________________________________________________________________
    C-x (                    | Begin recording macro.
    ESC a                    | Move to the beginning of the sentence that
                            | contains the point.
    C-SPACE                    | Set the mark.
    ESC e                    | Move the point to the end of the sentence.
    ESC w (or cmd-c)        | Copy region to the clipboard.
    C-x o*                    | Bring 'AlphaRefs' edit window to the front.
    C-y (or cmd-v)            | Paste clipboard in the 'AlphaRefs' window.
    C-x o*                    | Return to the original window.
    C-x )                    | Stop recording.

*C-x o (otherThing) is used since Alpha does not record the text typed into
the status bar; changing the buffer with C-x b will require that you hit
RETURN to go to the 'AlphaRefs' window.  C-x o (otherThing), simply
cycles to the window immediately behind the current, front-most, window.
You will have to be careful that the target window is in the right place
before invoking this macro when using C-x o.

Now that you have recorded the macro, you want to make it more useful by
automatically finding the sentences that you wish to copy into the
'AlphaRefs' window.  First, name the macro.  (Use "Name Last Macro"; I
called the macro 'cpSent2otherWin', but feel free to name it whatever you
wish).  Next, open your prefs.tcl file (use the Config-> Preferences->
Edit Prefs File menu).  Place the cursor at the end of the prefs.tcl file
and choose "Dump Named Macro" from the Kbd Macros submenu and select
'cpSent2otherWin'.  The following proc (or something similar) will appear
in your prefs.tcl file.

    proc cpSent2otherWin {} {
        prevSentence
        setMark
        nextSentence
        copy
        otherThing
        paste
        bind::CarriageReturn
        otherThing
    }

The first thing you might wish to do is change the name of the procedure
so that there is no confusion between the macro (whose definition is
stored in the arrdefs.tcl file in your Alpha preferences folder) and your
modifications of it.  You will also want a way to activate the procedure: a
key binding is the simplest way to invoke your procedure.  The following
will bind the procedure 'cpSent2otherWina' to ctrl-opt-f (0x03 is the key
code for 'f').

    # ctrl-opt-f
    Bind 0x03 <oz> cpSent2otherWina

The code for automatically finding the sentences you want to copy is
simple.  Let's assume that you wish to copy all the sentences with the word
'Alpha' in them to the 'AlphaRefs' window.  You will need to use a search
command.  The simplest way to proceed is to show you the modified
procedure, then explain what each line does (the line numbers are merely
for reference purposes and should not be included in your procedure).

    proc cpSent2otherWina {} {
2        set pos [getPos]
3        set theText [search -f 1 -m 0 -s -i 1 "Alpha" $pos]
4        eval select $theText

        prevSentence
        setMark
        nextSentence
        copy
        otherThing
        paste
        bind::CarriageReturn
        otherThing

15        goto [pos::math [lindex $theText 1] + 1]
    }

Line 2 uses the AlphaTcl command 'getPos' to return the value of the
current position of the insertion point.  This position value is a number
(in units of bytes) and is stored in the variable 'pos'.  Next, line 3 does
the search (you should take a look at the description of search in 'Alpha
Commands' to find out what the flags mean).  The result of the search is
two values: the initial position of the found text and the final position
of the found text.  Search doesn't move the insertion point, so line 4
accomplishes this by selecting the found text.  The following lines are the
same as the original macro.  Line 15 is not necessary since the call to
nextSentence moves the insertion point beyond the found text, but if our
macro did not move the point, then some line like 15 would be necessary to
set up the procedure to be called again without manually moving the point.
Line 15 uses pos::math to move the point 1 byte past the found text.

          Writing Good Macros

With practice you will become proficient at constructing macros which work
in all situations.  The most important principle in creating good macros
is the use of absolute, rather than relative commands.  In the above
double-space example, we used C-e to move to the end of the line rather
than spacing to the end of the line with a series of C-fs.  A good macro
will successfully work on the target text and prepare itself to be
repeated.  In the above example, the last command in the macro moves the
cursor to the next line, precisely where it needs to be for the a repeat
performance.

While macros are an easy way to automate repetitive typing tasks, they are
not an alternative for writing your own procedures.  There are many things
that you can't do with a macro.  Loops, if-then conditionals, and searches
cannot be recorded with a macro.  However, some macros might be good
starting points for scripting your own procedures.

          Things That Don't Work

Emacs users will be used to setting up a macro with a search, C-s,
command.  Alpha is not Emacs!  Text typed into the status bar is not
recorded.  The command C-s (quickFind) is recorded, but none of the search
text is.  In order to couple your macro with a search you will have to
learn a little Tcl (as shown above).

Recursive edits do not work in Alpha.  All keystrokes you type during macro
recording are a collected.  (A recursive edit in Emacs is invoked with C-x
q or C-u C-x q and provides a way to pause the macro for user enterable
text.  While in the recursive edit, the keystrokes are not recorded.
During the macro playback, the macro will pause for the user to enter text
when the recursive edit is encountered.)

          Differences Between Alpha and Emacs

In the double-space example, we used C-e C-f to position the cursor on the
next line.  C-n is just as good in Alpha; unlike Emacs, Alpha does not add a
new line to the buffer if C-n is issued on the last line of the file. If
you use C-n in Alpha and call the macro more times than there are lines in
the file no extra lines are added.


    ======================================================================


 Author: Donavan Hall
 E-mail: <[e-mail]>